.TH lha_build 1 "1 May 2012" "TrueCL Commands"

.SH NAME
lha_build \- Build or Change Cluster Configuration

.SH SYNOPSIS
.TS
l l.
lha_build	\fB-N|--node\fP \fIX\fP \fB--action\fP \fIadd\fP|\fIremove\fP|\fImodify\fP  [\fB--ips\fP [+|-]\fIip,...\fP]
	[\fB--appchange\fP] [\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--listattr\fP
or:
lha_build	\fB--setattr\fP \fIATTR:VALUE\fP
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--diskhb\fP \fB--info\fP [+|-]\fIname:node:dev\fP... 
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--diskhb\fP \fB--newhbkeys\fP
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--diskhb\fP \fB--validate\fP
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--connections\fP [+|-]\fIip:timeout,...\fP
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_build	\fB--synclvm\fP
	[\fB--force\fP] [\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP]
	[\fB--timeout\fP \fIN\fP] [\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_build(1)\fP is used to configure new clusters and make changes to an 
existing configuration once built. Once the very basic cluster configuration has been
completed (via the "setup" tools), this is the main tool handles core cluster configuration.

As can be seen from the above usage table it can be run in one of several available modes:

.SS Add/Remove or Changes Nodes in Cluster
Once a cluster request daemon has been configured on a node then that node can be 
added, changed or removed from actually belonging to a valid cluster definition.

Notice that this is combined with defining, adding or removing IP addresses to associate with 
the node. These can be different from those details defined for the Cluster Request Daemon
configuration for that node but often are not.

.SS Change Cluster Attribute Values
Whilst the cluster is being defined, or once it has been created and is in use, a large number
of paramaeters can be changed. In almost all cases these values are dynamic and impacted cluster
daemons will be reconfigured to use these new values as soon as the command is issued.

.SS Configure or Change Cluster Disk Heartbeats
If the hardware environment has access to shared storage (such as iSCSI or fibre channel) then
it is possible for a single device to be mapped to all nodes. They can then each read/write
particular sections and use the device for crude communication and heartbeats even if all
networks fail.

There are options to define new devices; generate new keys (which nodes use to ensure they 
are writing to the correct location!) and validate the device configuration too.

.SS Add/Remove or Change Known Connections
Known Connections are a list of IP addresses or Hostnames that are for
contactable devices outside of the cluster itself which the cluster nodes can
use to determine whether they are actually have no network connectivity or help
determine whether instead a node is down.

.SS Validate Cluster/Application/volume Manger Configuration
TrueCL works closely with the volume managers on a platform and typically keeps track 
of volume details and sizes (to ensure replication and online resizing functionality works
as expected).

This facility checks that all nodes/applications use the same storage details compared to
what is physically defined - and reports any differences.

.SH ARGUMENTS
.TP 8
--node
The name of the node (aka host) to define, change or remove from the cluster.
You can also modified the existing IP connection details for a node too.

Typically this is used initially to define a node and might be called several times
to define further IP addresses to communicate with the node in question.

It is strongly recommended that multiple IP addresses (via multiple networks) are 
configuration for each node.

.TP
--action
Indicates whether a node is being added, changed or removed from the cluster via the
values "add", "modify" or "remove" respectively. Nodes can be added to the cluster
(once a cluster request daemon is running on it) at any time; the cluster does not
need to be down.

Nodes can be modified at any time too; (indicating the IP connectivity details are
changing). This can be done whilst the cluster is up and running too.

Finally it is possible to remove a node from a cluster definition and althought the
cluster can be up the node in question should not define any application unless the
\fB--appchange\fP flag is specified too.
This is the name of the application to create or update. Multiple \fIlha_buildapp(1)\fP
commands can be used to used to define the application, so the command will obviously
work if the application is defined already.

If this is a new application there are two parameters that are expected to be used
to define the storage during the initial application configuration that takes place:

.TP
--appchange
If the number of nodes in the cluster has been reduced then by default the command
will fail if that node currently is defined as a valid node for hosting one or
more applications defined in the cluster. Supplying this argument will change the
behaviour to automatically reconfigure those applications as part of this process
so the nodes in question are not defined for those applications.

.TP
--ips
This is used to specifiy the definition, addition or removal of IP addresses that
the cluser processes use to communication with the node in question (as specified
via the \fI--node\fP parameter. If the first character is a '+' then the IP addresses
(or hostnames) are added to the list kept for the server. If '-' they are removed
from the server definition. 

Without the '+' or '-' these values define the list of IP addresses to use to
communicate with the server. The changes are dynamic - as soon as the command completes
all daemons will be reconfigured to take account of the changes.

.TP
--listattr
Simply lists all attributes that cab be used with the \fI--setattr\fP argument with this
command.

.TP
--setattr
This allows one or more attributes in the cluster to be modified. This argument is followed
by a pattern in the form of ATTRIBUTE:VALUE. This argument can be specified multiple 
times to perform multiple changes using the same command.

Each attribute may require different daemons to be reconfigured to take advantage
of the changes - this will be dealt with automatically by the command. The result being 
that all changes are considered dynamic. 

A full list of attributes that can be changed can be printed by the utility by using the
\fI--listattr\fP argument.

.TP
--diskhb
This indicates that an action is going to take place against the disk heartbeat
configuration; the actual defined by one of the three following arguments:
.RS 8
.TP 4
--info
Add, change or remove details of a particular disk heartbeat configuration 
for a particular server. The argument specified is a comma-separated list where
each element is a colon separated value of "heartbeat name", host and device name.

The initial letter of the argument might be '+' to add (or update) the existing heartbeat details,
it may be '-' to remove from existing details. Without either of the '-' or '+' this
particular heartbeat is defined.

An example might be --info 

--info hb1:node1:/dev/rdsk/raw1,hb1:node2:/dev/vx/rdmp/rawdisk1

.TP
--newhbkeys
Writes out a new key for the heartbeat device and records it in the configuration database.
.TP
--validate
Performs a full disk heartbeat validation. This process ensures that all devices defined 
for a heartbeat can read the expected key from all hosts, that all devices can write to
their expected offsets on their device settings.

Only if all tests are completed successfully will a disk heartbeat be considered valid and be
started such that all heartbeat daemons in the cluster will begin writing to it.
.RE

.TP 8
--connections
Updates the list of IP addresses that are defined as suitable for pinging if necessary
to ascertain whether the cluster has a general networking issue or whether node
communication to a particular node might instead be the issue.

As usual the list may be prefixed with '+' to add to the existing settings, '-' to remove
from the existing settings or without either the list of connections is redefined to this
value.

The timeout is in secods and can be a fraction. Hence a valid argument value
might be: 'printer1:0.5,fax2:1.0'. Notice any device specified must be available for
ICMP ping from all nodes in question.

.TP
--synclvm
Checks the hosts in the cluster and the relevant logical volume manager configuration
and reports any differences it can find between what has been stored in the cluster
configuration compared to what is currently runing.

.TP
--timeout
The amount of time to wait for certain responses to requests that are 
necessary for the relevant actions or checked to be performed. If this is not specified it will
default to 10 [seconds].
.TP
--debug
Run the \fIlha_build(1)\fP utility with debug levels of output - this is useful for
problem diagnosis or development of the software and is not recomended for
day-to-day use.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of cluster environment modification or validation.
This is the recommended flag if the administrator wishes to see any output.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during attempted change of the 
cluster configuration.

.SH OUTPUT
None of the actions for the cluster build output significant amounts of data unless
 the \fB--debug\fP option is used. It is strongly recommended that teh \fB--verbose\fP
option is used if output or progress information is desired.

All outputs takes place to the standard output device apart from errors which will
appear on the standard error channel.

.SH EXIT CODES
If the specified change or validation is successful then the return code will
be 0 - otherwise 1 or more indicates some sort of failure has occured. In such
situations the output will be include details of the error that caused the
failure return code.

.SH FILES
The utility uses the cluster request daemons to handle all changes. Hence any 
changes, problems or errors will be found in the log files for that
daemon, available on each node in the cluster. 

In the changes in question require reconfiguration of deaemons than other
daemon logs (listed below) may contain useful information too.

.TS
l l.
clreqd.log	Standard log file for messages.
clreqd.stdout	Will contain any standard output text for the application.
clreqd.stderr	Will contain any error output text for the application.
hbd.log	Heartbeat daemon main log file.
hbd.stdout	Heartbeat daemon standard output log.
hbd.stderr	Heartbeat daemon standard error log (program errors?)
.TE

.SH NOTES
Remember all settings only exist whilst the cluster is running. If the cluster is
stopped and restarted any changes will be lost and settings will return to default.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2012, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR clreq(1),
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_buildapp(1),
.BR lha_destroyapp(1),
.BR lha_migrateapp(1),
.BR lha_startapp(1).
.BR lha_stopapp(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

